// -*-c++-*- Copyright (C) 2011 osgPango Development Team
// $Id: Export 152 2011-07-26 14:49:02Z cubicool $

//! \file
//! \brief Main doxygen docs; also defines compiler signature exports.

#ifndef OSGPANGO_EXPORT_
#define OSGPANGO_EXPORT_

//! \mainpage osgPango NodeKit Documentation
//!
//! \section intro Introduction
//!
//! osgPango is C++ glueware between the excellent <a href='http://pango.org'>Pango C library</a>
//! and the <a href='http://openscenegraph.org'>OpenSceneGraph</a>. It uses a small chunk of the
//! GTK "stack" to run, but I assure you that the trouble in managing these dependencies is well
//! worth it when you realize what osgPango is capable of doing with your text in OSG. :) Furthermore,
//! like the binary library bundle provided by Mike Wieblen for the dependencies necessary on Windows
//! for building OSG proper, I too will offer a prebuilt bundle of osgPango's needed libraries compiled
//! using MSVC2008. Compililation on Linux is, of course, a non-issue.
//!
//! A final interesting note about Pango itself: Pango can actually take advantage of whatever
//! native rendering system is available to it. That is, on Linux Pango uses the FreeType code for
//! all of it's rendering, but on Windows it uses the new ClearType backend. (On Mac's I believe
//! the backend is called ATSUI, but don't quote me on that. :)) You can, however, build and
//! configure FreeType on all of these operating systems, and you may enjoy the consistency using
//! a single rendering backend for Pango provides. Currently there is no API in osgPango for choosing
//! the Pango rendering engine, though that will be added eventually to Context::init().
//!
//! \section about Brief Technical Overview
//!
//! The user creates and configures the global osgPango Context singleton. Such
//! a call looks something like the following:
//! 
//! \code
//! 	osgPango::Context::instance().init(...)
//! \endcode 
//!
//! There are various quality options you can use at this point, and I recommend
//! experimenting with them. This Context can only be initialized once.
//!
//! The user creates an instance of something derived from osgPango::Text, since
//! osgPango::Text is a virtual interface class and cannot be added to a scene
//! directly. For convenience I've written a simple osgPango::TextTransform object,
//! though you will probably end up creating your own class eventually. To do this,
//! extend osgPango::Text and override the "finalize" method, which is where you
//! should traverse the _ggMap variable and actually do something with the Geometry
//! you find. It's really that simple.
//! 
//! After creating a Text object, the user begins to call the addText method. This
//! method adds a string of Pango Markup formatted text at the specified offsets 
//! and using the various tidbits of the TextOptions struct which is, optionally,
//! passed in as the 4th and final argument. Each Text object can only be rendered
//! to a single GlyphRenderer object, though this may change in the future.
//! 
//! It should be noted that what the user is REALLY doing here is simply asking
//! the osgPango::Text object to create osg::Geometry objects internally and store
//! them in it's protected _ggMap member. This Geometry (large groups of quads) is
//! positioned and textured appropriately using the Pango layout engine, which
//! communicates with osgPango via Context::drawGlyphs. As indicated in the
//! source, this is the bridging function between Pango itself and our wrapper
//! library. Context::drawGlyphs is called as often as the low-level Pango engine
//! deems necessary. Thus, the routine must be modular, although for this reason
//! osgPango should not be called simultaneously from different threads.
//! 
//! The _ggMap (Glyph Geometry Map) member is a std::map object that creates an
//! std::pair key using the GlyphCache object and the current font color.
//! In simpler terms, all text using the same GlyphCache object and using the
//! same color is grouped together into the same osg::Geometry (technically,
//! I use a derived version of osg::Geometry, but it doesn't) vector object.
//! This vector of osg::Geometry objects is where the real data is, and the
//! index at which any group of quads is stored corresponds to the texture ID
//! in the parenting GlyphCache object.
//! 
//! \section usage A Quick Example
//! 
//! \include docs/demo.cpp

#if defined(_MSC_VER) || defined(__CYGWIN__) || defined(__MINGW32__) || defined( __BCPLUSPLUS__)  || defined( __MWERKS__)
    #if defined( osgPango_EXPORTS )
    #	define OSGPANGO_EXPORT   __declspec(dllexport)
    #else
    #	define OSGPANGO_EXPORT   __declspec(dllimport)
    #endif
    #define OSGPANGO_ENCODING osgText::String::ENCODING_UTF16
#else
    #define OSGPANGO_EXPORT
    #define OSGPANGO_ENCODING osgText::String::ENCODING_UTF8
#endif  

#endif
